// Copyright Keith D Gregory
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package org.sabayframework.mem.impl.file;

import java.nio.ByteBuffer;

/**
 * This interface defines a methods for absolute access to a byte-oriented
 * buffer. Its purpose is to allow code to use either a ByteBuffer (typically
 * for testing) or a MappedFileBuffer. All methods use a long index. However,
 * depending on the actual implementation, index values may be limited to
 * Integer.MAX_VALUE.
 * */
public interface LongByteBuffer {

	/**
	 * Returns the single byte at the specified index (relative to the
	 * relocation base).
	 * */
	byte get(long index);

	/**
	 * Updates the single byte at the specified index (relative to the
	 * relocation base).
	 * */
	void put(long index, byte value);

	/**
	 * Returns the 2-byte short value at the specified index (relative to the
	 * relocation base).
	 * */
	short getShort(long index);

	/**
	 * Sets the 2-byte short value at the specified index (relative to the
	 * relocation base).
	 * */
	void putShort(long index, short value);

	/**
	 * Returns the 4-byte int value at the specified index (relative to the
	 * relocation base).
	 * */
	int getInt(long index);

	/**
	 * Sets the 4-byte int value at the specified index (relative to the
	 * relocation base).
	 * */
	void putInt(long index, int value);

	/**
	 * Returns the 8-byte long value at the specified index (relative to the
	 * relocation base).
	 * */
	long getLong(long index);

	/**
	 * Sets the 8-byte long value at the specified index (relative to the
	 * relocation base).
	 * */
	void putLong(long index, long value);

	/**
	 * Returns the 4-byte float value at the specified index (relative to the
	 * relocation base).
	 * */
	float getFloat(long index);

	/**
	 * Sets the 4-byte float value at the specified index (relative to the
	 * relocation base).
	 * */
	void putFloat(long index, float value);

	/**
	 * Returns the 8-byte double value at the specified index (relative to the
	 * relocation base).
	 * */
	double getDouble(long index);

	/**
	 * Sets the 8-byte double value at the specified index (relative to the
	 * relocation base).
	 * */
	void putDouble(long index, double value);

	/**
	 * Returns the 2-byte char value at the specified index (relative to the
	 * relocation base).
	 * */
	char getChar(long index);

	/**
	 * Sets the 2-byte char value at the specified index (relative to the
	 * relocation base).
	 * */
	void putChar(long index, char value);

	/**
	 * Returns an array containing the len bytes starting at the specified index
	 * (relative to the relocation base).
	 * */
	byte[] getBytes(long index, int len);

	/**
	 * Inserts the specified array into the buffer, starting at the given index
	 * (relative to the relocation base).
	 * */
	void putBytes(long index, byte[] value);

	/**
	 * Returns a ByteBuffer that represents a slice of the underlying buffer
	 * (ie, shares the same backing store), starting at the given index
	 * (relative to the relocation base) and extending to the end of the
	 * underlying buffer. The semantics of this method depend on the underlying
	 * buffer. For a normal ByteBuffer, the limit will be determined by the size
	 * of the original buffer. For a MappedFileBuffer, the limit will depend on
	 * the particular segment containing the offset.
	 * */
	ByteBuffer slice(long index);

	/**
	 * Returns the capacity of the wrapped buffer.
	 * */
	long capacity();

	/**
	 * Returns the limit of the buffer: the highest legal index + 1. Will be <=
	 * capacity(). Support for this method will depend on the underlying
	 * buffer's support for limits. MappedFileBuffer does not support limits,
	 * and will always return capacity.
	 * */
	long limit();
}
